<!DOCTYPE html>
<html>
   <head>
      <!-- Update title -->
      <title>Hello Cinder: Chapter 2</title>

      <!-- keywords used for searching -->
      <meta name="keywords" content="guide, intro, tour, hello">
      <meta name="viewport" content="width=device-width, initial-scale=1">

      <!-- reference to Cinder classes -->
         <!-- <ci seealso dox="[CLASS NAME GOES HERE]" label="[NAME OF LINK]"></ci> -->

         <!-- master stylesheet - these links will be replaced when compiled -->
      <link rel="stylesheet" href="../../_assets/css/foundation.css">
      <link rel="stylesheet" href="../../_assets/css/prism.css">
      <link rel="stylesheet" href="../../_assets/css/style.css">
      <link href='http://fonts.googleapis.com/css?family=Open+Sans:400,300,600,700' rel='stylesheet' type='text/css'>

      <!-- Place additional stylsheet links here, which will be copied over when compiled (optional) -->
      
   </head>

   <body id="guide-contents" class="language-c++">

      <!-- CONTENT STARTS HERE -->
            <h1><a class="anchor" id="gridParticles"></a>
               Lining up the Particles
            </h1>
            <p>As we discussed in the previous chapter, our <code>Particle</code>s have a location, direction, speed, and radius. However, instead of spawning the <code>Particle</code>s in a random location, we are going to create an evenly spaced grid of <code>Particle</code>s.<br />
               <br />
               Our project window is currently set to 800x600 so we will create a grid of 80x60 <code>Particle</code>s. This will give us 10 pixels between each <code>Particle</code> for a total count of 4800. Previously, we used <code>ParticleController::addParticles( int amt )</code> to populate our list. We are going to make a similarly named method that will lay the <code>Particle</code>s out in a grid.<br />
            </p>
            <div class="fragment">
               <div class="line"><span class="keywordtype">void</span> ParticleController::addParticle( <span class="keywordtype">int</span> xi, <span class="keywordtype">int</span> yi ) {</div>
               <div class="line">  <span class="keywordtype">float</span> x = ( xi + 0.5f ) * 10.0f;</div>
               <div class="line">  <span class="keywordtype">float</span> y = ( yi + 0.5f ) * 10.0f;</div>
               <div class="line">  mParticles.push_back( Particle( Vec2f( x, y ) ) );</div>
               <div class="line">}</div>
            </div>
            <!-- fragment -->
            <p> <br />
               The addition of 0.5f is just a way to make sure the grid of <code>Particle</code>s is centered on screen. Try removing the 0.5f to see the difference. <br />
               Inside the <code>ParticleController</code> constructor, we add a nested for-loop which will call <code>addParticle( x, y )</code> 4800 times. 
            </p>
            <div class="fragment">
               <div class="line"><span class="keywordflow">for</span>( <span class="keywordtype">int</span> y=0; y&lt;mYRes; y++ ){</div>
               <div class="line">  <span class="keywordflow">for</span>( <span class="keywordtype">int</span> x=0; x&lt;mXRes; x++ ){</div>
               <div class="line">    addParticle( x, y );</div>
               <div class="line">  }</div>
               <div class="line">}</div>
            </div>
            <!-- fragment -->
            <p> <br /></p>
            <div class="image">
               <img src="images/tutorial_part2_01.png" alt="tutorial_part2_01.png"/>
            </div>
            <p> <br />
               Since each <code>Particle</code> controls its own variables, we can create remarkably complex (looking) results by simply adding one or two additional instructions for the <code>Particle</code>s to execute.<br />
               <br />
               For example, if we wanted each <code>Particle</code> to have a random radius, we need only to add a single line of code. That is a deceptively powerful realization. One line of code is all it takes to modify the look of thousands of individuals.<br />
               <br />
               Just to clarify, this is not a concept unique to Cinder. This is in no way a new or personal epiphany. As I continue to develop this tutorial, the project is going to become more and more complex. I find it useful to point out key aspects of my process regardless of whether they might be obvious or not. This notion of creating a large number of individual objects, each with its own interpretation of a single set of instructions, is what the majority of my code explorations are based upon.<br />
               <br />
            </p>
            <div class="fragment">
               <div class="line">mRadius = <a class="code" href="namespacecinder.html#ab7637c0d6db3b9234d15be30c2e7ccb0">Rand::randFloat</a>( 1.0f, 5.0f );</div>
            </div>
            <!-- fragment -->
            <p> <br /></p>
            <div class="image">
               <img src="images/tutorial_part2_02.png" alt="tutorial_part2_02.png"/>
            </div>
            <p> <br />
               <a class="el" href="classcinder_1_1_rand.html">Rand</a> is a class that helps you create random numbers to your specifications. If you just want a random float between 0.0 and 1.0, you write: 
            </p>
            <div class="fragment">
               <div class="line"><span class="keywordtype">float</span> randomFloat = <a class="code" href="namespacecinder.html#ab7637c0d6db3b9234d15be30c2e7ccb0">Rand::randFloat</a>();</div>
            </div>
            <!-- fragment -->
            <p> <br />
               If you prefer to get a random float in a weirder range, you can do this: 
            </p>
            <div class="fragment">
               <div class="line"><span class="keywordtype">float</span> randomFloat = <a class="code" href="namespacecinder.html#ab7637c0d6db3b9234d15be30c2e7ccb0">Rand::randFloat</a>( 5.0f, 14.0f );</div>
            </div>
            <!-- fragment -->
            <p> <br />
               That will give you a random number between 5.0f and 14.0f. This also works for ints. And happily, you can do the same thing for 2D and 3D vectors. If you ask for a <a class="el" href="classcinder_1_1_rand.html#a85d4fb55999f83dc7d4af27347c433ff">randVec2f()</a>, you get a 2D vector that has a length of 1.0. In other words, you get a point located on a circle that has a radius of 1.0. If you use <a class="el" href="classcinder_1_1_rand.html#ab9facff19763d3376637a63f815910cd">randVec3f()</a>, you will get back a point located on the surface of a unit sphere.<br />
               <br />
            </p>
            <div class="fragment">
               <div class="line">mRadius = cos( mLoc.y * 0.1f ) + sin( mLoc.x * 0.1f ) + 2.0f;</div>
            </div>
            <!-- fragment -->
            <p> <br /></p>
            <div class="image">
               <img src="images/tutorial_part2_03.png" alt="tutorial_part2_03.png"/>
            </div>
            <p> <br /></p>
            <div class="fragment">
               <div class="line">mRadius = ( sin( mLoc.y * mLoc.x ) + 1.0f ) * 2.0f;</div>
            </div>
            <!-- fragment -->
            <p> <br /></p>
            <div class="image">
               <img src="images/tutorial_part2_04.png" alt="tutorial_part2_04.png"/>
            </div>
            <p> <br />
               This process is pretty much how I learned trig. I read all about <em>sine equals opposite over hypotenuse</em> in college but I didn't appreciate the nature of trigonometry until I started experimenting with code. My early days of creating generative graphics was about 10% creative thinking and 90% <em>"What if I stick sin(y) here? Hmmm, interesting. What if I stick cos(x) here? Hmmm. How about tan(x)? Oops, nope. How about sin( cos( sin(y*k) + cos(x*k) ) )? Oooh, nice!"</em>.<br />
               <br />
               Incidentally, sin( cos( sin(y*k) + cos(x*k) ) ) looks something like this: 
            </p>
            <div class="fragment">
               <div class="line"><span class="keywordtype">float</span> xyOffset = sin( cos( sin( mLoc.y * 0.3183f ) + cos( mLoc.x * 0.3183f ) ) ) + 1.0f;</div>
               <div class="line">mRadius = xyOffset * xyOffset * 1.8f;</div>
            </div>
            <!-- fragment -->
            <p> <br /></p>
            <div class="image">
               <img src="images/tutorial_part2_05.png" alt="tutorial_part2_05.png"/>
            </div>
            <p> <br />
               It is time to give our project some motion. We are going to use the same method that we used to oscillate the background clear color. <a class="el" href="namespacecinder_1_1app.html#ac9ac93a362ec7149815a860c0770b302" title="Returns the number seconds which have elapsed since the active App launched. ">getElapsedSeconds()</a> and <a class="el" href="namespacecinder_1_1app.html#af76ee9ed608078551bf9e7bc1c1cb950" title="Returns the number of animation frames which have elapsed since the active App launched. ">getElapsedFrames()</a> are extremely useful for prototyping some basic movement. 
            </p>
            <div class="fragment">
               <div class="line"><span class="keywordtype">float</span> time = <a class="code" href="namespacecinder_1_1app.html#ac9ac93a362ec7149815a860c0770b302">app::getElapsedSeconds</a>();</div>
            </div>
            <!-- fragment -->
            <p> <br />
               Since we are calling this in our <code>Particle</code> class, we need to tell the <code>Particle</code> class where it can find <a class="el" href="namespacecinder_1_1app.html#ac9ac93a362ec7149815a860c0770b302" title="Returns the number seconds which have elapsed since the active App launched. ">getElapsedSeconds()</a>. All we do is add this include line to the top of the <code>Particle</code> class. 
            </p>
            <div class="fragment">
               <div class="line"><span class="preprocessor">#include &quot;<a class="code" href="_app_basic_8h.html">cinder/app/AppBasic.h</a>&quot;</span></div>
            </div>
            <!-- fragment -->
            <p> <br /></p>
            <h1><a class="anchor" id="returnImage"></a>
               Recreating the Image with Particles
            </h1>
            <p>In the last section, we learned three different ways to load and display an image. In this section, we are going to combine the image and <code>Particle</code> engine to hopefully create something greater than the sum of the parts.<br />
               <br />
               We will start by replacing our <a class="el" href="namespacecinder_1_1gl.html#a4d7358261901ab45091a6b046ef507d5">gl::Texture</a> with a new class, the <a class="el" href="classcinder_1_1_channel_t.html">Channel</a>. This is a class which can be used for storing a grayscale image. Its name comes from the fact that its older brother, the <a class="el" href="classcinder_1_1_surface_t.html">Surface</a> represents a color image made up of individual color channels: red, green, blue and sometimes alpha. However we don't need all that data for our purposes - we just want a gray image, so using a <a class="el" href="classcinder_1_1_surface_t.html">Surface</a> is overkill. Also, although <a class="el" href="namespacecinder_1_1gl.html#a4d7358261901ab45091a6b046ef507d5">gl::Texture</a>s can be grayscale, we don't want to draw this image anymore - we want to get at its data. So instead of putting it on the graphics card, we want to store it in memory, which a <a class="el" href="classcinder_1_1_channel_t.html">Channel</a> is ideal for.<br />
               <br />
               Loading an image into a <a class="el" href="classcinder_1_1_channel_t.html">Channel</a> is practically the same as loading into a <a class="el" href="namespacecinder_1_1gl.html#a4d7358261901ab45091a6b046ef507d5">gl::Texture</a>. 
            </p>
            <div class="fragment">
               <div class="line">Url url( <span class="stringliteral">&quot;http://www.flight404.com/_images/paris.jpg&quot;</span> );</div>
               <div class="line">mChannel = <a class="code" href="namespacecinder.html#a55542066ef5e4df2176ef692419aa2dd">Channel32f</a>( <a class="code" href="namespacecinder.html#ad49aa427548e365f95336af782c2161a">loadImage</a>( <a class="code" href="namespacecinder.html#ac585fce4c1e96b04a400b5858b607909">loadUrl</a>( url ) ) );</div>
            </div>
            <!-- fragment -->
            <p> <br />
               It is the same as before except we create a <a class="el" href="classcinder_1_1_channel_t.html">Channel32f</a> instead of the <a class="el" href="namespacecinder_1_1gl.html#a4d7358261901ab45091a6b046ef507d5">gl::Texture</a>. The <em>32f</em> simply means the <a class="el" href="classcinder_1_1_channel_t.html">Channel</a> is made up of 32 bit floating point numbers. In this scheme, <code>1.0</code> represents white and <code>0</code> represents black.<br />
               <br />
               This next step is just begging to happen. Each <code>Particle</code> is going to reference the <a class="el" href="classcinder_1_1_channel_t.html">Channel</a> to see what color gray exists at that <code>Particle</code>'s location. It will then set its color to this grayscale value. 
            </p>
            <div class="fragment">
               <div class="line"><span class="keywordtype">void</span> Particle::update( <span class="keyword">const</span> <a class="code" href="namespacecinder.html#a55542066ef5e4df2176ef692419aa2dd">Channel32f</a> &amp;channel ) {</div>
               <div class="line">  <span class="keywordtype">float</span> gray = channel.getValue( mLoc );</div>
               <div class="line">  mColor = <a class="code" href="namespacecinder.html#a957e45ea5178e7c7264bfe19ba91992b">Color</a>( gray, gray, gray );</div>
               <div class="line">}</div>
            </div>
            <!-- fragment -->
            <p> <br />
               We pass in a reference to the <a class="el" href="classcinder_1_1_channel_t.html">Channel</a> and use <code>getValue()</code> to get the value of the <a class="el" href="classcinder_1_1_channel_t.html">Channel</a> at a specific location. We simplified things a bit by making the image the same size as the project window. Otherwise we would have to do some extra work to make sure the image fills the entire app window and that we don't try to access outside of the <a class="el" href="classcinder_1_1_channel_t.html">Channel</a>'s dimension. This is something we will address later in the tutorial series.<br />
               <br />
               Now that we have the color, we need to make sure OpenGL knows what color to draw our circle. We add this line to <code>render()</code> before we draw the solid circle.<br />
            </p>
            <div class="fragment">
               <div class="line"><a class="code" href="namespacecinder_1_1dx.html#af396a1e9182529bfe483e9a6b6125423">gl::color</a>( mColor );</div>
            </div>
            <!-- fragment -->
            <p> <br />
               Now, every single one of our <code>Particle</code>s has a new set of instructions to follow.<br />
               <br />
               Step 1) Find out the color from the <a class="el" href="classcinder_1_1_channel_t.html">Channel</a> which corresponds with my current location. <br />
               Step 2) Set my color to the returned <a class="el" href="classcinder_1_1_channel_t.html">Channel</a> color. <br />
               Step 3) Draw myself <br />
               Each of the 4800 <code>Particle</code>s goes through this set of instructions every frame. You might be thinking this is overkill. The <code>Particle</code> only needs to find out its color once. This could happen when each <code>Particle</code> is created and then you never need to make the calculation.<br />
               <br />
               This is entirely true. However, in a short while, we will want to animate some of these variables which means we will have to do these calculations every frame anyway. So in general, you should separate your variables and your constants. If a property is not going to change, just define it once and forget about it. However, if you need to animate this property over time, you should do this in the <a class="el" href="classcinder_1_1app_1_1_app.html#af4dd0c8459354a9ced7250ad2a97dc9e">update()</a> method which gets called every frame. <br />
               <br />
            </p>
            <div class="image">
               <img src="images/tutorial_part2_06.png" alt="tutorial_part2_06.png"/>
            </div>
            <p> <br />
               Well, that looks just about like we expected. Nothing special there. How about instead, we adjust each <code>Particle</code>'s size and leave the color white. The <code>Particle</code>s that should be brighter will be larger than the <code>Particle</code>s that should be dark. 
            </p>
            <div class="fragment">
               <div class="line"><span class="keywordtype">void</span> Particle::update( <span class="keyword">const</span> <a class="code" href="namespacecinder.html#a55542066ef5e4df2176ef692419aa2dd">Channel32f</a> &amp;channel ) {</div>
               <div class="line">  mRadius = channel.getValue( mLoc ) * 7.0f;</div>
               <div class="line">}</div>
            </div>
            <!-- fragment -->
            <p> <br />
               This code looks familiar enough. Pass in the reference to a <a class="el" href="classcinder_1_1_channel_t.html">Channel</a>, get the grayscale value at the <code>Particle</code>'s position, then set the radius to be equal to that value.<br />
               <br />
               A quick side-note about the demon that is the <em>magic number</em>. In the code above, I know exactly why I wrote <code>7.0</code>. Since <code>getData()</code> for a <a class="el" href="classcinder_1_1_channel_t.html">Channel32f</a> returns a value from <code>0.0</code> to <code>1.0</code>, I decided I wanted that range to be larger. I arbitrarily chose <code>7.0</code>.<br />
               <br />
               However, after a couple weeks of being away from the code I wrote, I may not remember why I wrote <code>7.0</code> or what that number is even supposed to represent. This doesn't necessarily mean you should replace all numbers with named constants. That would be overkill. Just be aware that when you use constants that are not defined (or at least, described with comments), you are potentially doing something you will regret later, and you are definitely doing something that other coders frown upon. Make an effort to minimize these <em>magic numbers</em> especially if you plan on sharing code with others.<br />
               <br />
               Instead of using <code>7.0</code>, I have created a member variable called <code>mScale</code> which I initialized to <code>7.0</code>. No more mystery. 
            </p>
            <div class="fragment">
               <div class="line"><span class="keywordtype">void</span> Particle::update( <span class="keyword">const</span> <a class="code" href="namespacecinder.html#a55542066ef5e4df2176ef692419aa2dd">Channel32f</a> &amp;channel ) {</div>
               <div class="line">  mRadius = channel.getValue( mLoc ) * mScale;</div>
               <div class="line">}</div>
            </div>
            <!-- fragment -->
            <p> <br /></p>
            <div class="image">
               <img src="images/tutorial_part2_07.png" alt="tutorial_part2_07.png"/>
            </div>
            <p> <br />
               It is time to give the user some control. <a class="el" href="hello_cinder_chapter3.html">Chapter 3</a> will explore some options for user input.<br />
               <br />
            </p>
      <!-- END CONTENT -->

      <!-- Scripts -->
      <script src="../../_assets/js/prism.js" type="text/javascript"></script>
      <!-- Place additional scripts here (optional) -->
      <!-- <script type="text/javascript"></script> -->

   </body>
</html> 